Summary

• add explicit tool access metadata for every published Supabase MCP tool
• export createToolAccessHints() and createOAuthScopeHints() to derive minimum scope hints from features, readOnly, and projectScoped
• document the new helper API and add focused unit coverage

Why this helps

Issue #239 asks for minimum OAuth scopes based on the active MCP configuration.

While working through this, I found that the hosted OAuth consent flow for https://mcp.supabase.com/mcp does not appear to live entirely inside this OSS repo. This PR therefore focuses on the part that is in-repo and can be made deterministic here: a shared source of truth for tool -> access requirements and helper functions that downstream auth / integration layers can consume.

That means this PR does not claim to fully fix the hosted consent screen by itself. Instead, it adds the groundwork needed to do that cleanly without duplicating scope logic elsewhere.

Notes

• createOAuthScopeHints() returns only scope families documented in the public Supabase OAuth scope guide by default
• includeInferred: true opt-in adds best-effort hints for Management API surfaces that are used by the MCP server but are not clearly listed in the public scope table yet
• execute_sql downgrades to database:read in readOnly mode to match the behavior discussed in list_tables requires database:write permission #152

Verification

• npm exec --yes pnpm@10.7.0 -- --filter @supabase/mcp-utils build
• npm exec --yes pnpm@10.7.0 -- --filter @supabase/mcp-server-supabase typecheck
• CI=1 npm exec --yes pnpm@10.7.0 -- --filter @supabase/mcp-server-supabase exec vitest run src/tools/tool-access.test.ts --reporter=basic
• npm exec --yes pnpm@10.7.0 -- --filter @supabase/mcp-server-supabase build